\defmodule {RandomStreamBase}

This class provides a convenient foundation on which RNGs can
be built. It implements all the methods which do not depend directly on
the generator itself, but only on its output, which is to be defined
by implementing the \texttt{abstract} method \texttt{nextValue}. In the present 
class, all methods returning random numbers directly or indirectly 
(\texttt{nextDouble}, \texttt{nextArrayOfDouble}, \texttt{nextInt} and
 \texttt{nextArrayOfInt}) call \texttt{nextValue}.  Thus, to define a subclass 
that implements a RNG, it suffices to implement \texttt{nextValue}, in addition
 to the \texttt{reset...} and \texttt{toString} methods.
Of course, the other methods may also be overridden for improved efficiency.

If the \texttt{nextValue} already generates numbers with a precision of
 53-bits or higher, then \method{nextDouble}{} can be overridden to improve 
the performance. The mechanism for increasing the precision assumes that
 \texttt{nextValue} returns at least 29 bits of precision, in which case 
the higher precision numbers will have roughly 52 bits of precision.
This mechanism was designed primarily for RNGs that return numbers with 
around 30 to 32 bits of precision.
% If the precision of \method{nextValue}{} is less than 24 bits, then
% \texttt{nextDouble}
% must be overridden, otherwise there will be a loss of precision in the 
% middle-order bits.

\class{RandomStreamBase} and its subclasses are implementing the \class{Serializable} interface.
Each class has a serial number wich represent the class version. 
For instance \texttt{70510} means that the last change was the \texttt{10th May 2007}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%
\bigskip\hrule

\begin{code}
\begin{hide}
/*
 * Class:        RandomStreamBase
 * Description:  Base class of all random number generators
 * Environment:  Java
 * Software:     SSJ 
 * Copyright (C) 2001  Pierre L'Ecuyer and Universite de Montreal
 * Organization: DIRO, Universite de Montreal
 * @author       
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   <a href="http://www.gnu.org/licenses">GPL licence site</a>.
 */
\end{hide}
package umontreal.iro.lecuyer.rng; \begin{hide}

import java.io.Serializable; \end{hide}

public abstract class RandomStreamBase implements CloneableRandomStream,
                                                  Serializable \begin{hide} {

   private static final long serialVersionUID = 70510L;
   //La date de modification a l'envers, lire 10/05/2007
   
   //constants
   protected static double invtwo24 = 5.9604644775390625e-8;  //2^(-24)
   private static double EPSILON = 5.5511151231257827e-17;    //2^(-54)

   protected String name = null;

   // prec53 keeps track if the precision has been increased or not.
   protected boolean prec53 = false;
   protected boolean anti = false;  // Deprecated.

\end{hide}

   public abstract void resetStartStream();
   public abstract void resetStartSubstream();
   public abstract void resetNextSubstream();
   public abstract String toString();
\end{code}
\begin{code}

   public void increasedPrecision (boolean incp) \begin{hide} {
      prec53 = incp;
   }\end{hide}
\end{code}
 \begin{tabb} After calling this method with \texttt{incp = true}, each call to 
  the RNG (direct or indirect) for this stream 
  will return a uniform random number with more bits of precision than what
  is returned by \texttt{nextValue},
  and will advance the state of the stream by 2 steps instead of 1
  (i.e., \texttt{nextValue} will be called twice for each random number).

  More precisely, if \texttt{s} is a stream of a subclass of 
  \texttt{RandomStreamBase}, when the precision has been increased,
  the instruction ``\texttt{u = s.nextDouble()}'',  is equivalent to
  ``\texttt{u = (s.nextValue() + s.nextValue()*fact) \%\ 1.0}'' 
  where the constant \texttt{fact} is equal to $2^{-24}$.
  This also applies when calling \texttt{nextDouble} indirectly
  (e.g., via \texttt{nextInt}, etc.).
  By default, or if this method is called again with \texttt{incp = false}, 
  each call to \texttt{nextDouble} for this stream advances the state by 1 step
  and returns the same number as \texttt{nextValue}.  
\end{tabb}
\begin{htmlonly}
  \param{incp}{if the generator will be set to high precision mode}
\end{htmlonly}
\begin{code}

   protected abstract double nextValue();
\end{code}
\begin{tabb}
  This method should return the next random number (between 0 and 1) 
  from the current stream.
  If the stream is set to the high precision mode 
  (\texttt{increasedPrecision(true)} was called), then each call to 
  \texttt{nextDouble} will call \texttt{nextValue} twice, otherwise it will
  call it only once. 
\end{tabb}
\begin{htmlonly}
 \return{a number in the interval (0,1)}
\end{htmlonly}
\begin{code}

   public double nextDouble() \begin{hide} {
      double u = nextValue();
      if (prec53)
         u = (u + nextValue() * invtwo24) % 1.0 + EPSILON;
      if(anti)
         return 1.0 - u;
      else
         return u;
   }\end{hide}
\end{code}
\begin{tabb} Returns a uniform random number between 0 and 1 from the stream. 
  Its behavior depends on the last call to \method{increasedPrecision}{}.
  The generators programmed in SSJ never return the values 0 or 1.
\end{tabb}
\begin{htmlonly}
  \return{a number in the interval (0,1)}
\end{htmlonly}
\begin{code}

   public void nextArrayOfDouble (double[] u, int start, int n) \begin{hide} {
      if(u.length == 0)
         throw new NullPointerException("The array must be initialized.");
      if (u.length < n + start)
         throw new IndexOutOfBoundsException("The array is too small.");
      if(start < 0)
         throw new IndexOutOfBoundsException("Must start at a " +
                                             "non-negative index.");
      if(n < 0)
         throw new IllegalArgumentException("Must have a non-negative " +
                                            "number of elements.");

      for(int ii = start; ii < start + n; ii++)
         u[ii] = nextDouble();
   }\end{hide}
\end{code} 
\begin{tabb} Calls \texttt{nextDouble} \texttt{n} times to fill the array \texttt{u}.
\end{tabb}
\begin{htmlonly}
  \param{u}{the array in which the numbers will be stored}
  \param{start}{the first index of \texttt{u} to be used}
  \param{n}{the number of random numbers to put in \texttt{u}}
\end{htmlonly}
\begin{code}
  
   public int nextInt (int i, int j) \begin{hide} {
      if(i > j)
         throw new IllegalArgumentException(i + " is larger than " +
                                            j + ".");
      // This works even for an interval [0, 2^31 - 1]. It would not with 
      // return i + (int)(nextDouble() * (j - i + 1));
      return i + (int)(nextDouble() * (j - i + 1.0));
   } \end{hide}
\end{code} 
\begin{tabb} Calls \texttt{nextDouble} once to create one integer between
  \texttt{i} and \texttt{j}. This method always uses the highest order bits
  of the random number. It should be overridden if a faster implementation 
  exists for the specific generator.
\end{tabb}
\begin{htmlonly}
  \param{i}{the smallest possible returned integer}
  \param{j}{the largest possible returned integer}
  \return{a random integer between i and j}
\end{htmlonly}
\begin{code}

   public void nextArrayOfInt (int i, int j, int[] u, int start, int n) \begin{hide} {
      if(u == null)
         throw new NullPointerException("The array must be " +
                                        "initialized.");
      if (u.length < n + start)
         throw new IndexOutOfBoundsException("The array is too small.");
      if(start < 0)
         throw new IndexOutOfBoundsException("Must start at a " +
                                             "non-negative index.");
      if(n < 0)
         throw new IllegalArgumentException("Must have a non-negative " +
                                            "number of elements.");

      for(int ii = start; ii < start + n; ii++)
         u[ii] = nextInt(i,j);
   } \end{hide}
\end{code} 
\begin{tabb} Calls \texttt{nextInt} \texttt{n} times to fill the array \texttt{u}.
  This method should be overridden if a faster implementation exists for
  the specific generator.
\end{tabb}
\begin{htmlonly}
  \param{i}{the smallest possible integer to put in \texttt{u}}
  \param{j}{the largest possible integer to put in \texttt{u}}
  \param{u}{the array in which the numbers will be stored}
  \param{start}{the first index of \texttt{u} to be used}
  \param{n}{the number of random numbers to put in \texttt{u}}
\end{htmlonly}

\begin{code}

   @Deprecated
   public String formatState() \begin{hide} {
      return toString();
   }\end{hide}
\end{code}
\begin{tabb} Use the \texttt{toString} method.
\end{tabb}
\begin{hide}
\begin{code}

   @Deprecated
   public String formatStateFull() {
      throw new UnsupportedOperationException (
            "   call the toStringFull() method instead.");
   }\end{code}
\begin{tabb} Use the \texttt{toStringFull} method.
\end{tabb}
\end{hide}
\begin{code}

   public RandomStreamBase clone() \begin{hide} {
      RandomStreamBase retour = null;
      try {
         retour = (RandomStreamBase)super.clone();
      }
      catch(CloneNotSupportedException cnse) {
         cnse.printStackTrace(System.err);
      }
      return retour;
   }\end{hide}
   \end{code}
 \begin{tabb} Clones the current generator and return its copy.
 \end{tabb}
 \begin{htmlonly}
   \return{A deep copy of the current generator}
\end{htmlonly}
\begin{code}
\begin{hide}
}
\end{hide}
\end{code}
